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A. INTRODUCTION 

The NASIS Development Workbook contains all the 
required system documentation. The major sections 
are: 

I. Installation Standards 

II. System Overviews 

III. Data Set Specifications 

IV. Program Design Specifications 

V. Retrieval System Reference Manual 

VI. System Messages 

VII. Operating Specifications 

VIII. Data Base Administrator Reference Manual 

B. INSTA1IATICN STANDARDS 

This section describes the standard approach to 
preparing system documentation and outlines program 
design and coding rules and conventions. Included are 
instructions for preparing all major specifications 
and suggestions for improving the quality and 

efficiency of the programming task. 

C. SYSTEM OVERVIEWS 

The system overviews are a management tool. They are 
directed toward informing management of a system*s 
capabilities and requirements and are written 

containing a minimum of technical terminologv. 

The intent of the overviews is to introduce the system 
features tc interested individuals. Therefore, each 
major component of the system is represented in the 
overviews section. Each overview contains a 

description of the component’s activities and role in 
the overall system. This description includes 
explanations of new terms and concepts, clarifying 
charts and diagrams and a discussion of the performance 
requirements and growth potential of the module. 
Performance requirements consist of assumptions about 
the environment (hardware and software) and 
input-output format. 


D 


DATA SET SPECIFICATIONS 
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The data set specifications describe, the content, 
format, and medium of communication of every data set 
required by the system. Thus, all relevant 

information pertinent to a particular data set is 
prepared in a standard form and centralized in a 
single document. The standard format is the 
following: 

1. Introduction 

This narrative notes identifying characteristics 
of the data and its file. It includes layout 
sheets and information in the following format: 

A. DATA SET NAME: Name as used in the Design 

Specifications. 

B. CHEATED BY: Name of the module in which the 

data set is originally prepared. 

C. TYPE OF FILE: One of the six identified in 

part 2 of the data set specifications. 

D. ORGANISATION: ISAM, tape sequential, etc. 

E. KEY IDENTIFIER (CONTROL FIELD) : Name of the 

field used for access to a record; also, 
length cf key field. 

F. FECORB IENGTH: Byte length; if variable, 

state the minimum record length. 

G. ELOCKING FACTOR: If unblocked, state *1*. 

H. PURPOSE: Describe the purpose of the data 

set, its general contents and any 

peculiarities or special features. 

2. Forms 

Because different types cf data sets do not 
reguire the same descriptive information, several 
different forms are needed to adequately specify 
data sets. Each of the six types of data sets is 
discussed separately below with the specific forms 
requirements for each indicated. 

a. Punched Cards 

Use the Multiple-Card Layout Form (X24-6599) 
to designate each separate distinct card 
format which has fixed fields. Each field 
should be indicated by vertical lines 
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surrounding the field. To identify the 
field, consecutively number each field, 
starting at the left <e.g., 1, 2 # ) . On a 
separate page, itemise each field ty number 
and identify the field name and the contents 
cf the field. Define the validation rules 
for those fields which appear only on the 
card and do not carry on into the system. 

for cards which are free format or contain 
variable fields, define the card layout using 
a tabular form which specifies the fieldname, 
the starting column (if appropriate) , the 
minimum and maximum field lengths, and the 
content. Also, indicate any field 
delimiters. 

b. formatted Print-outs 

Define the format for each distinct data set 
using the standard IBB printer spacing chart, 
form X20-1776. Print all headings in the 
exact postions in which they occur. Include 
any numeric editing or alphabetic character 
insertions which ALWAYS appear on the 
report. Should one data set have multiple 
print formats, use a separate form for each. 
In any case, each different and distinct LINE 
format must be indicated at least once for 
each data set. Be sure to indicate any 
special end-of-program or end-of-routine 
print-outs which can occur. In all cases, 
the layout format shall represent a sample 
report. 

c. Terminal Communication 

Rost terminal communication is in the form of 
prompting messages and responses which are 
fully described in the appropriate Design 
Specification. Thus, the particular format 
utilized need not be referenced through a 
lata Set Specification. 

Display outputs in restricted format, 
however, reguire description on the 
Proportional Record Layout Form (X2Q-1702) . 
Document each distinctly identifiable display 
format cn a separate form. Since terminal 
displays may not truly be data sets, the 
introductory page may not contain all the 
requested information. 
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Prepare 2 display formats in the manner 
specified above for print-out formats. Print 
headers cn the form with all fields indicated 
by X's. Indicate editing marks or constants 
in their respective positions. Indicate 
continuous streams of information broken into 
multiple lines with a block outlined by X’s 
and a printed notation within the block which 
defines its parameters and contents. Also, 
mark fields which always appear separate and 
distinct with a numerical reference. Define 
each of these fields cn a separate page, by 
number. 

Tables 

Some tables are used to communicate between 
modules; others are used internally. Most of 
the internally-used tables should be defined 
within the appropriate module Design 
Specification . 

Use this section to describe any tables, 
lists, or structures which are parameters to 
a routine or pass information between 
modules. Because of the nature of these 
elements, no particular form need be used to 
define them. However, the introductory page 
shall still be prepared. 

Structures can best be described by showing 
the elements of the structure in an indented 
hierarchical format, such as the structure 
would appear in a PL/I program. Define each 
element of the structure by either a line 
comment on the form or a narrative 
description on a separate page. 

Lists (arrays) typically contain recurring 
elemental items, each of the same format and 
size. To define a list, simply give the 
dimensions of the list (number of items, 
state maximum, if variable) and describe the 
detail for one element. This description 
includes name, length, and content of each 
field in a list element. 

In many cases, a structure can also be 
defined in tabular form. A set of related, 
but unlike, items might be grouped together 
to form a table. In these instances, the 
means of description is a columnar document. 
To standardize the format, apply the 
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followinq concept to each element: 

1. Indicate the starting character 
position, assuming the entire set of 
elements is a continuous character 
string. 

2. Denote the field name. 

3. Give the field length. 

<1. Describe the field content, indicating 

any particular values assignable to the 
field. 

To segregate the columns, use vertical lines 
and headers for each column. 

Non-Data Base Files 

The documentation for each data set includes 
the introductory page and one or more layout 
forms. If the file contains any fixed-length 
records, define the specific format on the 
System/360 Record Layout Worksheet 

(X20-171 1) . Indicate each field by vertical 
lines placed in the appropriate positions on 
the fctm. Number the fields consecutively 

(1, 2, etc.) and, on a separate page, itemize 
each field by number, with name, length, type 
(binary, EECDIC, etc.), and state content 
beside each field. 

Since variable-length records preclude the 
use of a fixed-format layout form, describe 
any files containing such records in a 

tabular format. In using a columnar format, 
all delimiters or field-length indicators 

must be mentioned for each applicable field. 
In seme cases, where only a few 
variable-length fields occur at the end of a 
record, it may be more beneficial to define 
the record using both a layout form, for 
fixed-length fields, and a table, for the 
variable-length fields. 

Some of the files may contain header and/or 
trailer records. For these include a 
separate layout form or table to describe 
the special record formats. In addition, 
mention any special conditions or 
considerations (special handling, 

checkpoints, etc.). 
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f. Data Base Files: 

tefine each data set in terms of the set of 
descriptors for that file. To accomplish the 
definition, a special descriptor layout has 
teen prepared and shall be used. The first 
specification in this section is the 
descriptor format for the descriptors, 
themselves. Included is the format of the 
descriptor header. 

retailed information for using the form for 
the descriptors can be obtained from the 
descriptor editor user's guide. 

PROGRAM DESIGN SPECIFICATIONS 

1. Overview 

This section contains the design specifications 
for the programs and modules within NASIS. Its 
purpose is to standardize the preparation of the 
specifications and to guide the program design. 

Each malor functional module within the system is 
a separate entity for documentation purposes. The 
design specifications shall contain a description 
of, and specifications for, all detail processing 
which occurs in the module. Sub-modules, 
reference tables and data sets which are common to 
several modules are documented separately. 

All modules dc not require narrative entries under 
each heading and fcr some generalized routines a 
variance from the standard approach may be 

necessary. However, in all cases, the unused 
headings shall still be included in the 

specifications and a 'NOT APPLICABLE' reference 
noted. This action removes all doubt that anyone 
omitted considerations relative to a heading and 
yields a positive response to each item. 

2, Format 

The standard outline is shown in the following 
chart : 

A. MODULE NAME 

B. ANALYST 

C. MODULE FUNCTION 
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D. CAT A REQUIREMENTS 

1. I/C Block Diagram 

2. Input Data Sets 

a. Parameter Cards 

b. Punched Card Input Files 

c. Input Files 

d. On-line Terminal Entries 

3. Output Data Sets 

a. Output Files 

b. On-line Terminal Displays 

c. Formatted Print-outs 

d. Punched Card Output Files 

4. Reference Tables 

E. PROCESSING REQUIREMENTS 

1. Top level Flowchart 

2. Narrative 

F. CODING SPECIFICATIONS 

1, Source Language 

2. Suggestions and Techniques 

The following paragraphs describe the content of 
each section: 

MODULE NAME Heading 

State a functional name for the module, e.g., 
MAINTENANCE, Following the functional name, state 
a pregram name, which is eight or fewer 

characters with the first character an M N", e.g,, 
NDBMNTN, After the program name state the module 
name, usually the same as the program name minus 
the leading "N". 

ANALYST Heading 

Record the name(s) of the individual^) who 

prepared the design specifications, 

MODULI FUNCTION Heading 

Use this heading to give a general description of 
what the module accomplishes. Limit the narrative 
to approximately one-fourth page of single-spaced 
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typed copy. 

DATA REQUIREMENTS Headinq 

Define all the input and output data sets, 

includinq any intermediate work-data sets. Also, 
specify any reference tables used by the module. 
If the nature of the module is such that some data 
sets are unknown until execution time, outline the 
classes of data sets that are expected. 

In sDecifyinq data sets, a name reference to the 
proper data set will suffice since all data sets 
are fully described in their own section of the 
Workbook. However, while details of the formats 
of common data sets are not necessary, the 

processing of the data must still be specified. 

I/O BI.0CK DIAGRAM Headinq 

To place the module in the proper perspective and 
to give an overall picture of the data flow, draw 

a separate block diagram of the module and all 

data sets referenced by the module. The symbols 
for the block diagram shall be obtained from the 
latest revision of the IBM template <Form 
X20-8C20) . 

INPUT DATA SETS Headinq 

Specify all input files. Describe in detail those 
Job Control cards which may affect the module. 

PARAMETER CARDS Heading 

Explain the functions which are controlled by each 
parameter that appears on each parameter card used 
by the module. In additition, include a table 
showinq the card format and a description of each 
field’s content. If applicable, as for a 

fixed-position format, standard Multiple-Card 

Layout Forms may be used. A sample format layout 
follows: 

1. Card Name - DATE 

2. Field - 1 

a. Columns 1-2 

b. Contents - Year 

3. Field - 2 

a. Columns 3-4 

b. Contents - Month 
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tl. etc. 

PUNCHED CARD INPUT FILES Heading 

Identify all punched card files defined in the 
Data Set Specifications section of the Workbook 
using the appropriate standard file name. 

INPUT FILES Heading 

Identify all input data sets by the appropriate 
standard file name. 

In the case of generalized modules, data sets 
cannot be identified by name. However, it is 
probable that a particular class of data sets is 
accessed by the module. Write a short paragraph 
defining the class or classes of input data sets, 
along with a general indication of how each class 
might be referenced or manipulated. 

ON-LINE TERMINAL ENTRIES Heading 

In many modules, certain responses or commands are 
issued from terminals. Although a particular 
sequence of fields of data may be expected, the 
actual format could be free. For purposes of 
documentation, state all response formats in terms 
of the generalized free format construction and 
indicate any necessary field delimiters. Use a 
table, such as the type specified for parameter 
cards, for the various entry formats. Since many 
responses are subject to particular execution time 
situations, actual values for the responses are 
specified as part of the Processing Requirements 
section. 

OUTPUT DATA SETS Reading 

Output from a module may consist of many different 
types of information in many different formats. 
Specify all data sets including terminal displays 
and card and printer output. Describe in detail 
those Job Control cards which can affect the 
module. 

OUTPUT FILES Heading 

All data base output files, with the possible 
exception of intermediate work files, are defined 
in the Data Set Specifications section of the 
Workbook. Identify by the appropriate standard 
file name all data sets output by the module. 
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Where work files are needed, determine whether the 
intermediate file is utilised by other modules in 
the system. If so, insert the specifications for 
the file in the Data Set Specifications section of 
the Workbook, If not, define the work file in 
detail, includinq the following information where 
applicable: 

1. File attributes 

a. organization 

fc. recording medium 

c. name 

2. Becord attributes 

a. key identifier 

b. length 

c. mode (fixed or variable) 

d. blocking factor 

3. Field attributes (per each field) 

a. length 

b. mode 

c. data type (alphabetic, etc.) 

d. position in record 

4. Other identifying information 

In the case of generalized modules, data sets 
cannct be identified by name. However, it is 
probable that a particular class of data sets is 
output by the module. Write a short paragraph to 
define the class, or classes, of output data sets, 
along with a general indication of how each class 
is prepared. 

ON-LIHE TEBHINAL DISPLAYS Headino 

Describe all specific display formats generated by 
this module. In those instances where displays 
are generalized messages whose values are set at 
execution time, show maximum field length 
attributes and data type attributes (alphabetic, 
etc.) and indicate a field name for reference by 
the Processing Bequirements section of the 
specification. 

where the display is a graph or has some other 
non-linear peculiarities, write a short paragraph 
to identify the function and oddities of the 
display. In all instances, assign an identifying 
name to each distinct format so that proper 
reference can be made within the Processing 
Bequirements section. 



PAGE 13 


FORMATTED PRINT-OUTS Heading 

All print data sets generated by this module are 
defined in the Data Set Specifications section of 
the Wcrkbcok. Identify them by the appropriate 
standard file name. Ho reference need be made to 
the various fields within the files since the 

Processing Requirements section of the 

specifications for this module contains the 

detailed processing steps necessary to produce the 
print outs. Should the print out require a 

special form or particular line spacing not 
mentioned in the Data Set Specifications, describe 
those requirements. 

PUNCHED CARD OUTPUT FILES Heading 

All punched card data sets generated by this 
module are in the Data Set Specifications section 
of the Workbook. Identify them by the appropriate 
standard file name. No reference need be made to 
the various fields within the file since the 

Processing Requirements section of the 

specifications for this module contains detailed 
processing steps to format the cards. Should a 
specially-designed card be needed which is not 
mentioned in the Data Set Specifications, describe 
it. 

REFERENCE TABIES Heading 

Define all tables needed by the module. The 

tables can be either local to this module only or 
global for use by several modules. In the latter 
case, define the table in detail in the Data Set 
Specifications section. 

The designer’s objective is to identify table 
usage; however, if the table is local to the 
module, detail table specifications must be 

stated. In providing this desiqn-level 

information, the designer shall; 

a. identify the table with a suitable name. 

b. identify the table organization, specifying 
callinq sequence or other means of access to 
the table. 

c. define each field in the table by length, 
mode (F or V) and data type. 

d. give content of each of the fields if the 
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table is used merely for reference* If the 
table is to be used for internal storage* 
then specify processing steps in the 
Processing Requirements section. 

If necessary for clarity* use a chart such as 
Table 1 in the Appendix. 


If the table is a true matrix or array of like 
elements rather than a centralized source of 
related information, specify the dimensions of the 
matrix* the format and length of each element* and 
the number of elements in each dimension. For all 
tables* precede the table specifications with a 
brief discussion of its function. 

PROCESSING REQUIREMENTS Heading 

Use this heading to present the functional 
specifications of the proqram. These 

specifications indicate the functions that the 
module will have to perform. 

The minimum documentation is a top-level flowchart 
and a module narrative which presents the 
functional specifications of the module in 
generally the same order in which they are 
executed. Use figures, decision tables, and 
additional lower-level flowcharts for clarity. 

TOP-LEVEL FLOWCHART Heading 

The flowchart drawn under this heading depicts on 
an overall basis* the flow of data through the 
various processing steps within the module. The 
symbols for all flowcharts drawn in the Processing 
Requirements section shall be obtained from the 
latest revision of the IBM template (Form 
X20-8C20) . 

In designing the flowchart* observe these ground 
rules : 

a. The loqical flow of the module proceeds from 

the upper left corner of the sheet to the 
lower right corner. If practical, avoid 
r iqht-tc-lef t and lower-to-upper 

processing. 

b. Use the standard symbols and conform to 
standard flowcharting conventions. 
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c. Show the logic of the module as one mainline 
of processing which governs performance of 
specific subroutines. Frame each subroutine 
or sub-function reference in a PREDEFINED 
PROCESS symbol with the name of the 
routine. 


NARRATIVE Heading 

The most critical section of any desiqn 
specification is that which defines the actual 
manipulation of the data. For this reason, the 
narrative shall be written in a manner which is 
simple and understandable, yet complete in 
sufficient detail. 


The data flow depicted in the top-level flowchart 
serves as a quide to the sequence of the written 
specifications. The mainline of the module is 
defined first, thus presenting a written overview 
of the processing. Present each of the 
sub-functions or subroutines, as indicated on the 
top-level flowchart, under sub headinqs which 
reference the name stated on the flowchart. 

Within each of the areas, prepare specifications 
of reguired processing for that area. 

On occasion, complete written description is 
extremely difficult to prepare. In those cases, 
supplementary material may be helpful. Decision 
tables, illustrative charts, tables, and, 
particularly, detail-level flowcharts may be 
useful. Any such detail flowcharts are to follow 
the conventions described in the paragraphs 3.d-f. 
below. However, since the sole purpose of the 
Narrative section is to adequately specify ALL the 
processing required by the module, the written 
documentation is a primary requirement, while 
other means of presentation serve merely to 
clarifv the narrative. 

Since the Data Requirements Section makes no 
attempt to define the processing required to use 
or format I/O, this section is to specify all 
manipulation of data fields. State formatting of 
output records, generation of table entries, and 
manipulation of input records field by field. 

CODING SPECIFICATIONS Heading 

Although the job of the analyst is to specify what 
is to be dene and not how to do it, certain 
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aspects of the implementation can often be 
foreseen. State these points affecting the 
programming phase. 

SOURCE LANGUAGE Heading 

The installation may ase only one coding language, 
in which case this heading becomes superfluous. 
Often, however, one language may be favored over 
another for a particular module because of some 
special attributes of the language or efficiency 
considerations. State the language suggested for 
usage. If certain sub-modules are programmed in a 
different language, identify each sub-module and 
give valid reasons for its difference. 

SUGGESTIONS AND TECHNIQUES Heading 

While the intent of the Proqram Design 
Specifications is not to design the intricate 
details of a program, it often is the case that 
the analyst bases various portions of his design 
on certain implementation techniques. Document 
any suggestions for efficient methods of coding 
certain intricate routines and any techniques for 
handling especially complex processing. Assume 
the programmer is competent in good coding 
techniques and, thus, document only special 
situations. 

General 

In applying the format for writing Program Design 
Specifications, certain general conventions shall 
be observed. 

a. Type all documentation, including charts, 
graphs, and tables, but excluding 
flowcharts, on standard Neoterics, Inc. 
specifications forms. 

b. Insert inapplicable headings and document as 
"Not Applicable". 

c. Write narrative using complete sentences and 
good paragraph structure. 

d. Prepare flowcharts on plain Neoterics paper 
using the standard symbols on the IBM 
template number X20-8Q20. Charts proceed 
from top to bottom and from left to right. 

e. Each page of flowcharts is self-contained. 
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That is, show a routine from beginning to end 
cn one page (if possible) . Since many 
routines have too ouch detail for one page, 
the first page of the flowcharts for that 
routine depicts the total flow of the 

routine with any necessary subroutines 
indicated as a "predefined process." These 
subroutines are then charted on other pages. 
The entire set of flowcharts then is nested 
where the charts become progressively more 
detailed. In this method, no interpage 
connectors are necessary. To provide 

reference points for any detailed 
subroutines, each "predefined process" 
symbol contains the page number of the page 
showing the detail of the subroutine. 

f. Arrowheads shall appear on right to left and 
bottom to top directional lines. Use of 
arrowheads cn other lines is optional and 
shculd be omitted except where required for 
clarity. 

PROGRAMMING CONVENTIONS 

1. Overview: This section defines the coding 

conventions and format for the modules within 
NASIS, Its purpose is to provide a programming 
standard which yields code that is consistently 
structured, adequately documented, and easily 
readable. 

Separate conventions are discussed for each 
language used. Where practicable, however, 

formats and structures are consistent between the 
languages. 

Prime targets fcr standardization include 
comments, statement labels, data area structure, 
and program names and line numbers. Additional 
consideration is given to the use of optional 
symbols and key words for documentation purposes, 
to placements of the various sections of the 
coding, and to the identification of program 
sections or sub-modules via line-spacing and 

comment headers. 

2. Language Independent: When coding; Print all 

letters as capitals; The letter "aye" is "I"; the 
number "one" is "1"; The letter "oh" is "0"; the 
number "zero" is "0". The letter "zee" is " "; 
the number "two" is "2". Distinguish the letters 
"U" and "V" carefully. Distinguish the letter S 
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and the number 5 carefully; 

Limit each line of coding in either PL/I or 
Assembler tc columns 1-72. Of course, PL/I 
conventions require the first codinq character to 
appear in column 2. Use columns 73-80 of each 
line to contain either the line number or the 
modification date. This data is automatically 
entered by a utility program, which is defined 
later in this section, and should not be entered 
by the coder. 

Use comments liberally throughout all modules. 
Each module in the system shall have proper 

identification. The information which should be 
designated as part of the identification is; 

a. TITLE - includes both a six-character module 
name and a one-line module identifier. 

b. COMPANY - is "NEOTERXCS, INC. 

CLEVELAND, OHIC. " 

c. AUTHOR - identifies the name of the 
programmer (s) . If necessary, use initials. 

d. CLIENT - is "NASA LEWIS RESEARCH CENTER." 

e. SYSTEM - is "NASA AEROSPACE SAFETY 

INFORMATION SYSTEM (NASIS)." 

f. FUNCTION - describe, in a short paragraph, 
the purpose and general data flow of the 
module. 

Source Language Utility Routine 

A source language utility program is provided to 
enable the programmer to maintain a current, 
sequenced version of his module. In coding, do 
not enter any line sequence information. 

This utility provides a reorganized and 

resequenced line data set for the source language 
and maintains the current version number and date. 
Thus each modification belongs to a particular 
version. 

Once the source module has been formatted into a 
line data set, modifications and additions to the 
module are applied directly to the line data set. 
During the compiling phase of module development, 
there is no requirement to use the utility. 
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However, it is to be executed often enough for 
each module to maintain a reasonable level of 
currency in the sequencing of line numbers. 

4. Language Dependent 

An important consideration in coding is tc provide 
a module which can be readily modified or 
maintained. Thus, coding must be modular and well 
documented. Extra time and care expended in the 
original coding phase can save many hours of time 
during debugging or maintenance. The conventions 
enumerated below in separate language-dependent 
categories exist to help the programmer produce a 
well-structured, self-documenting, and easily 
readable nodule. 

5. ASSEMEL1 LANGUAGE 

Several conventions concerning the actual format 
of the ceding are to; Begin be followed. all 
statement and data labels in column 1; Begin 
operation codes or macro calls in column 
10; Eegin operands in column 16. (Macros may 
need an eight-character operation. In this case, 
operands start in column 19) ; Begin comments in 
column 36. Each line of code should be 
commented; 

To easily identify sub-modules or subroutines, 
certain organization conventions are to be 
practiced. Eegin all sub-modules or subroutines 
on a new page on the assembly listing; Within 
long routines, plan the coding so that a section 
never crosses a page boundary of the assembled 
listing; Precede each section with a one-line 
comment describing the function of the section. 

Within the structure dictated by the above 
conventions, utilize the following standards in 
coding the modules. 

All coding must be re-entrant; Use the standard 
System/360 linkage conventions for all 
subroutines. These rules can be found in the IBM 
Assembler Language Programmer's Guide; The module 
CSECT should be read-only and contain only 
executable instructions. Betain all data and 
constants in the PSECT; Within the PSECT, group 
the various types of non-executable coding by 
category. (i.e., all file areas together, all 
work areas together, all equivalences together, 
etc,); Identify each file area or structure with 
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a comment card which precedes the area; Invent 
meaningful labels for both data and instruction 
statements in terms of the value or function they 
represent. Co not use nondescript labels, such as 
people’s names or objects; Define literals, 
either string or arithmetic, used more than once 
in the context of the instructions via a data 
statement or an equivalence prior to its use. 
(e.g., the character should be defined using 

an equivalence with the label 

"ASTERISK") . Minimize the use of instruction 
counter references. Use of this feature of the 
language is warranted only in cases where the 
reference point is within one or two instructions 
of the instruction having the reference; Hake all 
register references svmbolic and conform to the 
labels R0-R15 for registers 0-15; The standard 
base register for the PSECT is R13; for the CSECT, 
B11, Assign additional base registers as 
desired. 

Three macros are available, and should be used, to 
assist in the standardization of the modules. 

a. CBSTAHT - Code this macro at the very 

beginning of the module. Its format is: 

label DBSTART (CSECT entry points) , 

(CSECT base registers) , 
(PSECT base registers) 

where up to thirty-two entry points, six 
CSECT registers and six PSECT registers can 
be specified. Separate multiple operands 
with commas, 

b. IBENTBY - Code this macro as the first 

instruction in the CSECT defined by the entry 
points indicated in DBSTART. Its format is: 

label DBENTBY entry point name 

c. E BEX IT - Place this macro at the end of the 
CSECT defined by the entry points indicated 
in DBSTART. Its format is: 

Label DBEXIT 

All assemblies are to contain both an object 
listing and a cross-reference listing, A symbol 
listing is net required in the debugging phase but 
is to be contained in the final version of the 
module . 
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PI /I 

The format of these modules shall conform to the 
following rules; All coding must be 
re-entrant; Begin all statement labels in column 
2 of a separate line of code. (Column 1 is used 
for listing carriage control.); Begin the text of 
each statement (apart from any label) in column 5 
of a new line, subject to the indentation rules 
which are indicated below; Comment each line to 
the extent possible. If the line is short enough 
to permit it, start the comment in column 41. If 
the comment is too long for the available space, 
continue it on the next succeeding line; Use 
indentation to emphasize data and statement 
relationships and to provide coding which is 
easily read and understood. Format data 
structures so that each subordinate level is 
indented four columns from the margin of the next 
higher level.. Start the THEN and ELSE clauses of 
the IF statement on a new coding line indented 
four columns from the margin of the associated IF. 
Use another four-column indentation for nested IF 
statements. 

Procedures and segments within a module should be 
easily identifiable. Construct a descriptive 
header for each segment or procedure in the 
following format; 

One procedure name definition card containing 
a comment of continuous asterisks following 
the name and an eject page carriage control 
character; 

One blank comment card or a zero in column 1 
cf the next card; 

Cne or more comment cards describing the 
segment and, if necessary, any parameters 
being passed through the routine; 

One blank comment card or a zero in column 
cne of the following card; 

Cne comment card containing a continuous 
string of asterisks; 

If the routine is not a procedure, use a segment 
label instead of a procedure name on the first 
card of the header. The first line of statement 
text then immediatelv succeeds the header. This 
convention effectively provides a description box 
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for each routine. 

Standardization of the organization and content of 
the coding provides easy readinq and understanding 
of the modules. Observe these coding rules: 

a. Ceclare all variables. 

b. Position all DECLARE statements immediately 
after the PROCEDURE or BEGIN statements of a 
block (succeeding any special requirements 
such as a KINCIODE LISFHAC(DB); statement 
when using DBPL/I) . 

c. Code nc more than one statement on a coding 
line. 

d. Qualify all references to minor structures 
and structure elements, at least, by the 
malor structure name. 









